註解無法彌補糟糕的程式碼

Uncle Bob：「寫註解的其中一個動機，是因為程式碼寫的太糟糕」

如果真的遇到糟糕的程式碼，且不是在非常緊急的狀況下，請好好的把裡面邏輯一層一層的剝開，然後重構他。而不是一味的加上註解。
在維護程式碼時，也要記得同時維護註解呦!

註解不是越多越好

//Bad，每條程式碼都提的話，閱讀100行程式碼就會不小心變成200行...

function hashIt(data) {
  // The hash
  let hash = 0;

  // Length of string
  const length = data.length;

  // Loop through every character in data
  for (let i = 0; i < length; i++) {
    // Get character code.
    const char = data.charCodeAt(i);
    // Make the hash
    hash = (hash << 5) - hash + char;
    // Convert to 32-bit integer
    hash &= hash;
  }
}

//Better，只下必要的註解

function hashIt(data) {
  let hash = 0;
  const length = data.length;

  for (let i = 0; i < length; i++) {
    const char = data.charCodeAt(i);
    hash = (hash << 5) - hash + char;

    // Convert to 32-bit integer
    hash &= hash;
  }
}

有益的註解 - 法律型

有時候去看開源的程式碼都會看到這種著作權聲明

# Copyright 2023 XXXX. All Rights Reserved.
# 
# Licensed under XXX
# ...

有益的註解 - 對意圖的解釋

function hashIt(data) {
  let hash = 0;
  const length = data.length;

  for (let i = 0; i < length; i++) {
    const char = data.charCodeAt(i);
    hash = (hash << 5) - hash + char;

    // Convert to 32-bit integer
    hash &= hash;
  }
}

有益的註解 - docstring

/**
* This function subtracts two numbers
* @param {number} a - The first number
* @param {number} b - The second number
* @returns {number} The difference between the two numbers
*/

function subtractNumbers(a, b) {
  return a - b;
}

糟糕的註解 — 干擾型註解

我懷疑你把自己燜壞了…

const getUserBMI = (height , weight) => {

	//世界衛生組織建議以身體質量指數（Body Mass Index, BMI）來衡量肥胖程度，
	//其計算公式是以體重（公斤）除以身高（公尺）的平方。
	//這是我在維基百科查的

	return ( weight/(height * height)).toFixed(2)

	//寫完了，噢耶！！

}

糟糕的註解 — 以前註解掉的function

如果已經棄用或是重新命名重構的function，那請將痕跡擦乾淨，上完大號不會忘記要擦屁股吧

// Bad

doIt();
// justDoIt();
// DoItYourSelf();

糟糕的註解 — 自我風格型

如果沒有嗑的話，請不要這樣，我會覺得你壓力很大….

/////////////////////////////////////////////////////////////////
//////////////////////我是註解，下面的程式是我寫的拉////////////////
/////////////////////////////////////////////////////////////////

function stupidComment(){
//...
}

當然註解還是有許多方法，但要記住的是，只在必要的情況下寫註解，然後不要亂來。

編排的作用就跟我們看文章的格式一樣，排版越清晰就越容易閱讀，我們在寫程式碼應該也要注重一下排版，當然每個人都有自己習慣的排版，但請將你的程式碼排版統一。

我們也可以利用prettier這類的套件來讓我們的程式碼間隔一致

編排

垂直編排

作者提到：「一個被呼叫的函式，應該要出現在『執行呼叫的函式』的下方。」

這邊我自己的習慣是 function 跟 function 中間會有一行的間距

水平編排

有兩種 ：

//第一種 

let apple = "apple";
let pineapple = "pineapple";
let mango = "mango"

//第二種

let apple        = "apple";
let pineapple    = "pineapple";
let mango        = "mango"

我自己的習慣是使用第一種拉，這個就個人喜好了，老話一句，統一就好

該多長？

畢竟 code 不是跟房貸一樣越長越好，該多長呢 ? 不要使用到水平卷軸為主。

• 寬度建議不超過120字元

還有像運算子可以在左右兩旁多給他的空白鍵，提高程式碼的閱讀性

function sum (a,b){
	return a+b;
}

function sum (a, b){
	return a + b;
}

有好的編排不僅在溝通上可以少很多時間成本，還有可能增加開發的效率。
因為註解跟編排每個人、每間公司習慣不一樣，但都是老話一句，統一就好。